fix: raise a clear exception when adapt data and the data mask disagree - #399

Companion to PyAutoGalaxy#516 / PyAutoLabs/PyAutoGalaxy#517 — the legibility half of that fix.

Summary

An adapt image defined on a different mask to the data cannot be indexed by the data's slim indexes. Until
now this surfaced as a bare IndexError several frames deep inside adaptive_pixel_signals_from:

mappers/mapper_util.py:62 adaptive_pixel_signals_from
    flat_data_vals = xp.take(adapt_data[slim_index_for_sub_slim_index], I_sub, axis=0)
IndexError: index 177 is out of bounds for axis 0 with size 177

Because slim indexes are ordered, the first out-of-range index equals the adapt data's length, so the
message always reads index N ... size N — which looks like a classic off-by-one in the indexing. It is
not: adaptive_pixel_signals_from is correct, and the real fault is a mask mismatch several layers up. The
2026-07-21 census filed exactly this misdiagnosis.

Mapper.pixel_signals_from now checks the lengths up front and raises an InversionException naming the
likely cause (a stale adapt-image cache) and the remedy. A loud crash, not a silent guard — no fallback, no
clamping, no None handling.

Test changes

Two existing tests passed an unmasked 49-pixel adapt image (image_7x7) against a 9-pixel mask, which the
new check correctly rejects:

• test__adaptive_pixel_signals_from___matches_util
• test__pixel_signals_from__rectangular_adapt_density_mesh__matches_util

Both now build the adapt image on the data's own mask, as a real fit does. Their assertions are unchanged —
the fixture was all-ones, so which entries were indexed never affected the result, which is why the
mismatch went unnoticed.

Adds test__pixel_signals_from__adapt_data_on_a_different_mask__raises_clear_exception.

pytest test_autoarray — 927 passed.

API Changes

Mapper.pixel_signals_from raises exc.InversionException when len(adapt_data) differs from
over_sampler.mask.pixels_in_mask. This input was already broken — it previously raised IndexError from
the same call — so no working caller changes behaviour. Callers catching IndexError around this path would
need to catch InversionException instead; none exist in the stack.

No signature, name or return-value changes.

🤖 Generated with Claude Code